/*
Copyright 2008 Todd Ditchendorf. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted 
provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions 
and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of 
conditions and the following disclaimer in the documentation and/or other materials provided 
with the distribution.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TODD DITCHENDORF OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.
*/

//
//  TODBrowserPlugIn.h
//  FluidInstance
//
//  Created by Todd Ditchendorf on 3/8/08.
//  Copyright 2008 Todd Ditchendorf. All rights reserved.
//

#import <Cocoa/Cocoa.h>

extern NSString *TODBrowserTabDidCloseNotification;
extern NSString *TODBrowserTabDidOpenNotification;
extern NSString *TODBrowserTabSelectionChangedNotification;

extern NSString *TODBrowserWebViewDidCommitLoadForMainFrameNotification;
extern NSString *TODBrowserWebViewDidChangeProgressEstimateForMainFrameNotification;
extern NSString *TODBrowserWebViewDidFinishLoadForMainFrameNotification;
extern NSString *TODBrowserWebViewDidFailLoadForMainFrameNotification;

// Notification names
extern NSString *TODBrowserPlugInViewControllerWillAppearNotifcation;
extern NSString *TODBrowserPlugInViewControllerDidAppearNotifcation;
extern NSString *TODBrowserPlugInViewControllerWillDisappearNotifcation;
extern NSString *TODBrowserPlugInViewControllerDidDisappearNotifcation;

// keys for the userInfo dictionary of Notifications sent with names from above
extern NSString *TODBrowserPlugInCurrentViewPlacementMaskKey;		// NSInteger
extern NSString *TODBrowserPlugInKey;								// id <TODBrowserPlugIn>
extern NSString *TODBrowserPlugInViewControllerKey;					// NSViewController
extern NSString *TODBrowserPlugInViewControllerDrawerKey;			// NSDrawer -- this is only sent for view controllers currently in a drawer position

@protocol TODBrowserPlugInController;

typedef enum {
	TODBrowserPlugInViewPlacementDrawerMask = 1 << 1,
	TODBrowserPlugInViewPlacementUtilityPanelMask = 1 << 2,
	TODBrowserPlugInViewPlacementFloatingUtilityPanelMask = 1 << 3,
	TODBrowserPlugInViewPlacementHUDPanelMask = 1 << 4,
	TODBrowserPlugInViewPlacementFloatingHUDPanelMask = 1 << 5,
	TODBrowserPlugInViewPlacementSplitViewBottomMask = 1 << 6,
	TODBrowserPlugInViewPlacementSplitViewLeftMask = 1 << 7,
	TODBrowserPlugInViewPlacementSplitViewRightMask = 1 << 8,
	TODBrowserPlugInViewPlacementSplitViewTopMask = 1 << 9,
} TODBrowserPlugInViewPlacementMask;

// note that your impl of this protocol will be registered (by the Fluid SSB) for the four PlugInViewController notifications below
// your impl will also be registered (by the Fluid SSB) for all NSWindow Notifications on the window with which it is associated, if it responds to the appropriate callback selectors
// you can implement the NSWindowNotification callback methods if you like. they will be called if you do.
@protocol TODBrowserPlugIn <NSObject>

// the plugInController is this plugin's API back to the Fluid SSB application.
- (id)initWithBrowserPlugInController:(id <TODBrowserPlugInController>)plugInController;

// create a new NSViewController to display your plugin in a new window. 
// the returned object should be autoreleased. Fluid will retain it and then release it when its window is destroyed.
// This may be called multiple times - once for every window in which the user views your plugin.
- (NSViewController *)makePlugInViewController;

// return the single NSViewController which will control the 'Preferences' view that will appear in the Fluid Preferences window.
// only one should ever be created. you should probably create it lazily in your implementation of this method.
// returned object should be autoreleased.
- (NSViewController *)preferencesViewController;

// unique reverse domain. e.g.: com.fluidapp.FoobarPlugIn
- (NSString *)identifier;

// the display string title for this plugin. do not include 'Plug-in' in this string. Just the name of this plugin
// e.g.: 'Clipboard' rather than 'Clipboard Plug-in'.
- (NSString *)localizedTitle;

// an or'ed mask containing the UI placements allowed for this plugin
- (NSInteger)allowedViewPlacementMask;

// a single UI placement maks stating where this plugin should appear by default
- (NSInteger)preferredViewPlacementMask;

// a string that will be used as the 'keyboard shortcut' in the main menu item for this plugin
- (NSString *)preferredMenuItemKeyEquivalent;

// an or'd mask of modifiers to be usind in the keyboard shortcut in the main menu item for this plugin
// e.g.: (NSControlKeyMask|NSAlternateKeyMask|NSCommandKeyMask)
- (NSUInteger)preferredMenuItemKeyEquivalentModifierMask;

// a string matching the filename of an image in this plugin bundle's Resources dir.
// this string should not include the file extension.
- (NSString *)toolbarIconImageName;

// a string matching the filename of an image in this plugin bundle's Resources dir.
// this string should not include the file extension.
- (NSString *)preferencesIconImageName;

// values in this dictionary will be added to NSUserDefaults for the currently running SSB.
// the keys in this dictionary should be carefully namespaced
- (NSDictionary *)defaultsDictionary;

// a dictionary containing the standard keys and values provided as the 'options' arg to:
// -[NSApplication orderFrontStandardAboutPanelWithOptions:]. See Apple's documentation for that method.
- (NSDictionary *)aboutInfoDictionary;

@optional
- (CGFloat)preferredVerticalSplitPosition;
- (CGFloat)preferredHorizontalSplitPosition;
- (NSInteger)preferredToolbarButtonType;
@end

@interface NSObject (TODBrowserPlugInNotifications)
- (void)plugInViewControllerWillAppear:(NSNotification *)notification;
- (void)plugInViewControllerDidAppear:(NSNotification *)notification;
- (void)plugInViewControllerWillDisappear:(NSNotification *)notification;
- (void)plugInViewControllerDidDisappear:(NSNotification *)notification;
@end